home *** CD-ROM | disk | FTP | other *** search
/ Toolkit for Quake / Toolkit For Quake 1996-10.iso / quakec / howpatch.txt < prev   
Text File  |  1996-08-15  |  8KB  |  167 lines
  1. How to use and make QuakeC patch files
  2. by Jeff Epler <jepler@inetnebr.com>
  3. 3 August 1996
  4.  
  5. This is a draft, and probably isn't that great an explanation.  Please
  6. mail me with questions about the directions, or suggestions on how to
  7. improve this document.
  8.  
  9. Some parts of this document were contributed by Kyle R. Hofmann
  10. <rhofmann@crl.com>, and various other changes were also suggested via email.
  11.  
  12. You should always be able to find the newest version of this
  13. document at http://cse.unl.edu/~jepler/quakec/howpatch.txt.  If I
  14. take the time to make a hypertext version of this file, it will be at
  15. http://cse.unl.edu/~jepler/quakec/howpatch.html.  This file is also
  16. uploaded to ftp.cdrom.com.
  17.  
  18. How to use QuakeC patch files
  19. -----------------------------
  20.  
  21.    Get and install a version of patch suitable for your OS.  Under most
  22.    unicies, (including Linux) this is already available.  For DOS, you
  23.    want
  24.     ftp://oak.oakland.edu:/pub/simtelnet/gnu/djgpp/v2gnu/pat21b.zip
  25.    I don't know where a windows 95/nt version of patch resides, but the
  26.    DOS version should execute just fine.  If you want to compile your own
  27.    version of patch, get it from
  28.      ftp://prep.ai.mit.edu/pub/gnu/diffutils-2.7.tar.gz
  29.  
  30.    Get a version of qcc suitable for your OS.  Look around at
  31.     ftp://ftp.cdrom.com/pub/idgames/idstuff/source or
  32.     ftp://ftp.cdrom.com/pub/idgames2/quakec or
  33.     ftp://ftp.cdrom.com/pub/idgames2/utils for one.
  34.  
  35.    Get a patch file.  One such file will reside at
  36.     ftp://ftp.cdrom.com/pub/idgames2/quakec/monsters/friend.zip
  37.    Unzip it, and you'll get friend.pat.
  38.  
  39.    Put the patch.exe and qccdos.exe files in a directory in your PATH.
  40.  
  41.    Make a new directory and copy the unchanged files from v101qc to this
  42.    new directory.  Change to the new directory.  Unzip the patch file
  43.    (friend.zip) here, or move it from where you unzipped it. (If you are
  44.    smart or willing to spend much time, you can add several patches to
  45.    the same source, getting all the features.  However, there are likely
  46.    to be rejects [see below] or unwanted side effects of putting several
  47.    patches together)
  48.  
  49.      patch < friend.pat or
  50.      type friend.pat | patch
  51.  
  52.    Inspect the directory for any "rejected" patches.  If there are some,
  53.    you should use your favorite editor to inspect the reject file (named
  54.    under unix whatever.qc.rej, and under DOS whatever.qc#) and make by
  55.    hand the changes that are required.  + marks lines present in the
  56.    new version but not in the old, and - marks lines present in the old
  57.    but not in the new.  Ideally, you should have no rejected patches.
  58.    If you have many rejected patches, your command-line may have been
  59.    wrong for patch.  Files ending in ~ are backups of files changed by the
  60.    patch, and can generally be deleted.
  61.  
  62.    Run qcc to compile a new progs.dat (depending on the setup, progs.dat
  63.    may be created in the current directory or the parent directory.
  64.    Change the first line in progs.src to move where progs.dat will be
  65.    created), copy it to quake\whatever, and run quake -game whatever.
  66.    You're done.
  67.  
  68.    To undo a patch, use the command
  69.  
  70.      patch -R < friend.pat
  71.  
  72.    Make sure you type an uppercase R.
  73.  
  74. Errors installing QuakeC patches
  75. --------------------------------
  76.  
  77.   patch is not a perfect utility.  If the QuakeC source which you are
  78. trying to patch is already modified, or if the file has had lines added
  79. or subtracted to it, you may get errors.  In serious cases, you may get
  80. "rejected hunks", patches which could not be applied at all.  Warning and
  81. errors include:
  82.  
  83.   - Offsets.  Offsets are nothing much to be concerned about, usually.
  84.     They indicate that patch did not place the patch on the exact line
  85.     specified; instead, patch placed the patch several lines away.  This
  86.     is usually indicative of previously changed QuakeC sources, and in
  87.     most cases may be safely ignored.  However, if there is an
  88.     excessively large offset, you should check to make sure the patch has
  89.     been applied properly.
  90.  
  91.   - Fuzz factor.  Fuzz factor indicates that the exact context could not
  92.     be found, and so context lines at the beginning or end of the patch
  93.     were ignored.  Be suspicious of patches which have a fuzz factor.
  94.     Though they may be a result of changed sources, they can also be a
  95.     result of an improperly applied or created patch.  Be sure to check
  96.     to ensure that the patch is properly applied.
  97.  
  98.   - Rejected hunks.  Rejected hunks are sections of a patch which could
  99.     not be applied at all.  They will be named foo.qc.rej or foo.qc#
  100.     (replace foo with the filename of the .qc file which could not be
  101.     patched).  They may be hand applied by going to the lines specified
  102.     at the start of the hunk and the entire hunk being copied in.  If the
  103.     hunk is part of a context diff, be sure to install the second half;
  104.     that's the changed version (you can use the first half of the hunk
  105.     to determine where the patch should be applied).  If the hunk is part
  106.     of a unified diff, be sure to remove the sections with as - prefixing
  107.     them and remove the + prefixing other lines (but do not remove the
  108.     lines with the +'s)  However, be *extremely careful* --- rejected
  109.     hunks may be completely incompatible with the code you currently have
  110.     installed.
  111.  
  112. Installing multiple patch files
  113. -------------------------------
  114.  
  115.    Installing multiple patch files is easy and simple.  Simply get both
  116.    patches, and install them using the procedure listed above.  You will
  117.    most likely encounter some of the errors listed above.  In this case, do
  118.    not worry if it's simply a case of a minor offset.  Most likely the file
  119.    has been modified by both patches and you're seeing a side effect.  Worry
  120.    more if a fuzz factor is needed; it might indicate that the same portion
  121.    of code is being modified by two patches.  Worry most when a hunk is
  122.    rejected --- that usually indicates that the exact same portion of code
  123.    was modified by both patches.  It might make the two incompatible.
  124.  
  125.  
  126. How to make QuakeC patch files
  127. ------------------------------
  128.  
  129.    Get and install a copy of diff for your machine.  For unix, again it's
  130.    included.  For DOS, get
  131.     ftp://oak.oakland.edu/pub/simtelnet/gnu/djgpp/v2gnu/dif271b.zip
  132.    Again, I don't know about w95/w32/wnt, except that the dos version
  133.    should work in the dos box.
  134.  
  135.    Get a directory with your mods in it and a directory with v101qc source
  136.    side by side.
  137.  
  138.    diff -ur --new-file v101qc yourdir > yourdir.pat
  139.  
  140.    zip or otherwise compress yourdir.pat
  141.  
  142.    Share with the world.
  143.  
  144.    You should probably always diff against v101qc sources unless you have
  145.    a good reason not to.  When you diff against v101qc, anyone can use
  146.    those files and your .pat file to get a replica of your sources.  One
  147.    time to use a different set of 'old' files would be something like this:
  148.  
  149.      John Doe made code for a weapon that turned monsters into little dogs.
  150.      The only problem is that his files don't quite work -- Ammo can be
  151.      turned into a dog too.  You fix this up and want to let John know.  So
  152.      you make a diff like this:
  153.  
  154.      diff -ur --new-file jdgun yourgun > yourgun.pat
  155.  
  156.      Now, John Doe can see the differences between his gun code and your
  157.      gun code, and as a bonus the file is smaller.  You could also hand it
  158.      out to people who have his original gun diff as well.
  159.  
  160. Other problems
  161. --------------
  162.  
  163. If you get an error about being unable to create a file /tmp/paaaax
  164. (For instance), just create a \TMP directory on the drive where you were
  165. trying to run patch.  I don't know if having the TEMP or TMP environment
  166. variable set to an existing directory will also help this.
  167.